// DOC_DXY_Pages.h
//
// Copyright (c) 2010 Kim McKinley
// Author : Kim McKinley
//
// This file is processed with software developed by :
//  Doxygen (http://www.doxygen.org/).
//

namespace doc {
  namespace dxy {
/** @page Design 1) Design
 @image html progmodules.png
 @htmlonly
<p></p>

<p>This diagram shows the components of Scullery Server.</p>

<p></p>

<p><strong>Application</strong></p>

<p>This is the main application that is called by the operating system to start
the program. The Configuration instantiated and loaded. Default sub-directories
for databases and web sites are verified and created if required.</p>

<p>The Acceptor is instantiated and the first thread to start the Acceptor is
spawned. The main application thread then given the task of handling the
console commands from the user. Upon the user issuing a '.bye' command the
console handler exits and calls the Acceptor to shutdown. When the Acceptor
shutdown returns the program exits.</p>

<p></p>

<p><strong>Acceptor</strong></p>

<p>The Acceptor component is the network interface to the web server handlers.
The initial thread that is spawned by the application sets up the TCP/IP Listen
port. If the listen port is successfully created the thread will spawn another
thread to 'this' Acceptor and then waits on a network accept() for incoming
connections.</p>

<p>The second thread spawned by the initial thread does not need to set up the
Listen port, as that has already been done. It does check to see if the maximum
number of 'waiting' threads specified in the configuartion has been reached; if
not, it spawns but yet another thread for 'this' Acceptor. It then waits for a
connection from the network.</p>

<p>This cycle of spawning threads continues until the maximum number of waiting
threads has been reached. At that point a whole set of threads are waiting to
accept connections. These threads are used to process incoming requests from
the web browsers. When a web brower connects, one of the threads will be
activated by the OS to accept the connection. At this point the thread
accepting the connection will spawn another thread to take it's place to
waiting for another connection. The thread is now considered 'active' and is
responsible for receiving and processing the the request from the browser with
the help of the Handler.</p>

<p>The active thread will remain active until the browser drops the connection,
or it is dropped by the Handler due to inactivity timeout.</p>

<p></p>

<p><strong>Handler</strong></p>

<p>Handler controls the creation of the HTTP message, calling of web server
Extensions, and transmitting the reply back to the requesting browser. Each
Acceptor thread spawned creates a unique instance of a Handler. The Acceptor is
a 'friend' of and works in concert with the handler. In the case of Scullery
Server, the handler contains a HTTP instance and a list of web server
Extensions which use the data in the HTTP class to produce a reply. The handler
formats and transmits the reply.</p>

<p>The active Acceptor thread loads the Handler with data from the connection
and then calls the handler to process the request. Request processing is done
by the active thread to insure that each request coming over the connection is
performed sequentially. After the handler has delivered the reply it returns
the thread back to the Acceptor to receive the next request over the
connection. This continues until the either the browser drops the connection or
the connection is dropped due to inactivity timeout.</p>

<p>The Handler calls each extension sequentially until one of the extensions
returns indicating that the request has been processed. If all the extensions
indicate the request can not be processed the handler replies with a HTTP (404)
'Not Found' response.</p>

<p>Most commonly used browsers establish multiple connections which allows
concurrent processing of requests - of course, that is up to the browser.</p>

<p></p>

<p><strong>Http</strong></p>

<p>This class allows intuitive use of HTTP request and reply information by web
server Extensions.</p>

<p>The Http class parses a HTTP request and also holds the associated response
built by the Extensions. It is instantiated by the Handler for each request
received by the Acceptor. This component parses the browser request into STL
classes to be accessed by the Extensions, and allows the Handler to extract
reply information to format and send the HTTP response.</p>

<p>Data from the brower is parsed into std::string's and std::maps containing
the parameters of the request as well as the HTTP header fields. It is also
responsible for decoding any URL escape codes into the ascii character that the
code represents. Along with the request, the class contains a similar structure
that holds the response.</p>

<p></p>

<p><strong>Extensions</strong></p>

<p>Server functionality is extended by deriving from a very simple class
ExtendServer and adding that class to the list of extensions in the Handler.
The BuildContent() function of an extension is called by the Handler which
expects either a HTTP Response Code or -1 as a response indicating to continue
to the next extension.</p>
<ul>
  <li>FileContent 
    <dl>
      <dt>This extension allows Scullery to respond to basic web requests for
      html, script, and image files. It checks the HTTP path to insure that it
      is not accessing a directory that is not a sub-directory of Scullery. It
      then attempts to open the path as a file, if not successful the extension
      returns a -1 to indicate to the Handler to continue to the next
      extension. If successful the file attributes are checked to see if it has
      been modified since the last request for that file. If not modified the
      extension will return 304 'Not Modified', otherwise the file is read and
      loaded into the Http class and prepares to return 200 'OK'. The mime type
      is looked up and added as a HTTP header and finally returns to the
      Handler the appropriate Response Code. </dt>
    </dl>
  </li>
  <li>SqliteHtml 
    <dl>
      <dt>This extension formats the results from a SQLite select statement
      into an HTML table format. It would generally be used to return database
      data in response to AJAX requests for from a browser. The path is checked
      to see if the request is for /SqliteHtml, returning -1 if not for this
      extension. It tries to opens the database and submit the Select request
      to Sqlite to return HTML formatted results. If the Sqlite module throws
      an exception the error is reported HTML style. The results are streamed
      into the HTTP content with a return code of (200) 'OK'. (Note that it is
      up to brower scripts to determine if the returned result was successful
      or got an error.)</dt>
    </dl>
  </li>
  <li>SqliteXml 
    <dl>
      <dt>This extension returns an XML document based on the results of a
      SQLite statement. There are three paths that the extension handles,
      /Execute, /Query, and /Ping. Regardless of the path the XML response
      prolog and fields are prepared for the response. If the path is not found
      the response is cleared and as usual the extension returns -1. Each path
      preforms a differing action :</dt>
    </dl>
    <ul>
      <li>Execute 
        <dl>
          <dt>This executes any valid SQLite SQL command and returns the
          result. This path is generally used to process commands that do not
          return data, such as CREATE, DROP, etc.</dt>
        </dl>
      </li>
      <li>Query 
        <dl>
          <dt>This path would normally be used when the expected result
          contains data from a database.</dt>
        </dl>
      </li>
      <li>Ping 
        <dl>
          <dt>The Ping path can be used to test XML document parsing by the
          browser and to verify that the Scullery SQLite system is working
          properly. It returns an XML field containing a 'Pong' result.</dt>
        </dl>
      </li>
    </ul>
  </li>
  <dl>
    <dt>This extension formats the results from a SQLite select statement A
    summary is added to the end of the document with information about the SQL
    command executed and the extension returns a HTTP (200) 'OK' response.</dt>
  </dl>
  <li>ShowConsole 
    <dl>
      <dt>This extension simply shows the console window. Used to 
      redisplay the window after user issues a .hide command.</dt>
    </dl>
  </li>
</ul>

<p><strong>Configuration</strong></p>

<p>The configuration is stored as a global two dimensional stl::map that is
accessable by all classes in the application. The first parameter is the
section the second is the configuration option. To access the configuration
data use an expression like 'gConfig["DEFAULT"]["SERVER_PORT"]' which will
return a std::string of the server port that is in the default section. If a
configuration value is not found an empty std::string is returned.</p>

<p>All configuration parameters are loaded by the main application thread prior
to firing up any other threads. Note that the configuration is not protected by
a mutex so it is not thread safe for writing. Reading values can be done at any
time by any thread. To change the values the server would need to be
restarted.</p>

<p></p>
@endhtmlonly
*/

//-----------------------------------------------------------
/** @page SQLiteLib 2) SQLite Library
 @htmlonly
<p><strong>SQLite Library</strong></p><p>SQLite is compiled into the Scullery Server
program as opposed to building and statically or dynamically linking to the library.
The only modification to the SQLite code has been to rename the 'main()' functiion in
shell.c to 'sqlitemain'. This change is required to prevent the duplicate main() compiler
error. It also allows the user to run the SQLite command shell from the Scullery console.</p>

<p>To ease interfacing Scullery to SQLite a C++ Sqlite class is has been
implemented. The class provides access to the database as well as formatting
the results for use by Scullery.</p>

<p>A single instance of the SQLite library can be used by multiple threads due
to SQLite being compiled using the default 'Serialized' mode. Even with that
assurance, Sculley has been designed so the SQLite class instances are
instantiated, used, and destroyed by the thread that is processing the request.
If there are multiple requests concurrently accessing the same database, each
has it's own instance, so multiple threads should not be an issue. See
http://www.sqlite.org/threadsafe.html for a discussion of SQLite
multi-threading.</p>

<p></p>
@endhtmlonly
*/

//-----------------------------------------------------------
/** @page OSSpecific 3) Operating System Specific
@htmlonly
<p><strong>Operating System Specifics</strong></p>
<p>Scullery was initially written to run under Windows operation systems but
the code has been refactored numerous times. During these rewrites the code has
been designed to be adapted to other systems. To this end, the OS_Specific.h
file contains wrapper functions to OS specific functions that generally differ
between operating systems. These functions are wrappers for spawning threads,
handling system events, and mutexes. The idea is to ease the modifications
required to port Scullery to other compilers and operating systems.</p>

<p>As of this writing, the wrappers implement calls to Windows specific
functions. It has been planned to implement calls to other operating systems.
but has yet to be done.</p>

<p>That being said, there are some calls in the code, specifically to the '_s'
string functions that are Windows specific. These would also need to be
addressed when porting the software.</p>

<p>Another alternative would be to refactor the code and use a portable C++
library such as Boost http://www.boost.org/. At first blush, it appears that
such a project would almost require close a rewrite of the application, so that
has not been considered.</p>
@endhtmlonly
*/
/*
    \class circular_buffer
    \brief Circular buffer - a STL compliant container.
    \param T The type of the elements stored in the <code>circular_buffer</code>.
    \par Type Requirements T
         The <code>T</code> has to be <a href="http://www.sgi.com/tech/stl/Assignable.html">
         SGIAssignable</a> (SGI STL defined combination of <a href="../../utility/Assignable.html">
         Assignable</a> and <a href="../../utility/CopyConstructible.html">CopyConstructible</a>).
         Moreover <code>T</code> has to be <a href="http://www.sgi.com/tech/stl/DefaultConstructible.html">
         DefaultConstructible</a> if supplied as a default parameter when invoking some of the
         <code>circular_buffer</code>'s methods e.g.
         <code>insert(iterator pos, const value_type& item = %value_type())</code>. And
         <a href="http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</a> and/or
         <a href="../../utility/LessThanComparable.html">LessThanComparable</a> if the <code>circular_buffer</code>
         will be compared with another container.
    \param Alloc The allocator type used for all internal memory management.
    \par Type Requirements Alloc
         The <code>Alloc</code> has to meet the allocator requirements imposed by STL.
    \par Default Alloc
         std::allocator<T>

    For detailed documentation of the circular_buffer visit:
    http://www.boost.org/libs/circular_buffer/doc/circular_buffer.html

*/

//-----------------------------------------------------------
/** @page ThreadSafety 4) Thread Safety
@htmlonly
<p><strong>Thread Safety</strong></p>
<p>Mutexs have been intentionally kept to a minimum to both reduce overhead and
simplify code maintenance. Where possible threads instantiate, use, and
destruct their own classes eliminating the chance of thread collisions. The
notable exception is the Acceptor which controls the spawning and termination
as well as maintaining a record of threads.</p>

<p>The configuaration parameters are not thread safe for writting. Reading is
fine because configuration values are not updated once loaded upon application
startup. If the criteria that configuration parameters require update while the
Scullery is running, it would need to be mutex protected.</p>

<p>The most frequent modification to Scullery are adding and maintaining
Extensions. When building an extension care is taken to insure each instance
does not concurrently share data structures or classes with other threads
running in the application. If modifying an extension one should not have to
worry about thread locks.</p>
@endhtmlonly
*/

//-----------------------------------------------------------
/** @page security 5) Security
@htmlonly
<p>Scullery Server does not currently have a security layer implemented as it
would complicate the code and there are many options available that can run
external to the server. Scullery's purpose is to deliver web and database content
and care has been taken to stay focused on on that task.</p>

<p>There are open source SSL software, such as http://www.openssl.org that could
be layered onto Scullery if security is of concern. Another possibility is to use
a proxy server which provides the security layer.

Scullery has been verified as working behind an Apache Server configured as a proxy
server to Scullery AJAX requests.</p>
@endhtmlonly
*/

//-----------------------------------------------------------
/** @page customize 6) Customizing Scullery Server
@htmlonly

@endhtmlonly
*/

//-----------------------------------------------------------
/** @page DocNotes Documenter Notes

 @htmlonly
 <hr size="1">
 <p>This documentation focuses on 'what' PicoC functions do more than 'how' PicoC does it.  The documentation is not inline with the code but a separate project all together (in doxygen terminology it is called 'Structured Documentation').  Hopefully developers implementing <a href="http://code.google.com/p/Caiman/">PicoC</a> will find this presentation useful.</p>
 
<p>Caiman required a general purpose interpretive host language with the following properties :
<ul>
<li>Language that is executed dynamically (i.e.: Interpretive) </li>
<li>Easily interfaced with Caiman's command library</li>
<li>Scripts that are Caiman data objects</li>
<li>Ability to autonomously produce scripts</li>
<ul><li>Production of parametrized functional AI strategies 'on-the-fly'</li></ul>
<li>A language commonly known by the programming community</li>
<li>Not bound to a specific Operating System</li>
<li>Overridable standard I/O procedures</li>
<ul><li>Caiman redirects I/O via it's framework</li></ul>
<li>Tightly intergated with Caiman</li>
<ul><li>Complete integratation within the Caiman framework</li></ul>
<li>No independant download or install</li>
<li>Liberal licensing of source code</li>
<ul><li>Caiman and supporting software is Open Source</li></ul>
<li>Resonable interpretive and execution speed</li>
<li>MultiThreaded execution</li>
</ul>

</p>
 
  
 

 @endhtmlonly

*/

} // namespace dxy
} // namespace doc
